---
title: "MastraAuthFirebase Class | Auth"
description: "Documentation for the MastraAuthFirebase class, which authenticates Mastra applications using Firebase Authentication."
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# MastraAuthFirebase Class

The `MastraAuthFirebase` class provides authentication for Mastra using Firebase Authentication. It verifies incoming requests using Firebase ID tokens and integrates with the Mastra server using the `auth` option.

## Prerequisites

This example uses Firebase Authentication. Make sure to:

1. Create a Firebase project in the [Firebase Console](https://console.firebase.google.com/)
2. Enable Authentication and configure your preferred sign-in methods (Google, Email/Password, etc.)
3. Generate a service account key from Project Settings > Service Accounts
4. Download the service account JSON file

```env title=".env" copy
FIREBASE_SERVICE_ACCOUNT=/path/to/your/service-account-key.json
FIRESTORE_DATABASE_ID=(default)
# Alternative environment variable names:
# FIREBASE_DATABASE_ID=(default)
```

> **Note:** Store your service account JSON file securely and never commit it to version control.

## Installation

Before you can use the `MastraAuthFirebase` class you have to install the `@mastra/auth-firebase` package.

```bash copy
npm install @mastra/auth-firebase@beta
```

## Usage examples

### Basic usage with environment variables

If you set the required environment variables (`FIREBASE_SERVICE_ACCOUNT` and `FIRESTORE_DATABASE_ID`), you can initialize `MastraAuthFirebase` without any constructor arguments. The class will automatically read these environment variables as configuration:

```typescript {2,7} title="src/mastra/index.ts" showLineNumbers copy
import { Mastra } from "@mastra/core";
import { MastraAuthFirebase } from "@mastra/auth-firebase";

// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
export const mastra = new Mastra({
  // ..
  server: {
    auth: new MastraAuthFirebase(),
  },
});
```

### Custom configuration

```typescript {2,7-10} title="src/mastra/index.ts" showLineNumbers copy
import { Mastra } from "@mastra/core";
import { MastraAuthFirebase } from "@mastra/auth-firebase";

export const mastra = new Mastra({
  // ..
  server: {
    auth: new MastraAuthFirebase({
      serviceAccount: "/path/to/service-account.json",
      databaseId: "your-database-id",
    }),
  },
});
```

## Configuration

The `MastraAuthFirebase` class can be configured through constructor options or environment variables.

### Environment Variables

- `FIREBASE_SERVICE_ACCOUNT`: Path to Firebase service account JSON file
- `FIRESTORE_DATABASE_ID` or `FIREBASE_DATABASE_ID`: Firestore database ID

> **Note:** When constructor options are not provided, the class automatically reads these environment variables. This means you can simply call `new MastraAuthFirebase()` without any arguments if your environment variables are properly configured.

### User Authorization

By default, `MastraAuthFirebase` uses Firestore to manage user access. It expects a collection named `user_access` with documents keyed by user UIDs. The presence of a document in this collection determines whether a user is authorized.

```typescript title="firestore-structure.txt" copy
user_access/
  {user_uid_1}/     // Document exists = user authorized
  {user_uid_2}/     // Document exists = user authorized
```

To customize user authorization, provide a custom `authorizeUser` function:

```typescript title="src/mastra/auth.ts" showLineNumbers copy
import { MastraAuthFirebase } from "@mastra/auth-firebase";

const firebaseAuth = new MastraAuthFirebase({
  authorizeUser: async (user) => {
    // Custom authorization logic
    return user.email?.endsWith("@yourcompany.com") || false;
  },
});
```

> See the [MastraAuthFirebase](/reference/v1/auth/firebase) API reference for all available configuration options.

## Client-side setup

When using Firebase auth, you'll need to initialize Firebase on the client side, authenticate users, and retrieve their ID tokens to pass to your Mastra requests.

### Setting up Firebase on the client

First, initialize Firebase in your client application:

```typescript title="lib/firebase.ts" showLineNumbers copy
import { initializeApp } from "firebase/app";
import { getAuth, GoogleAuthProvider } from "firebase/auth";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
};

const app = initializeApp(firebaseConfig);
export const auth = getAuth(app);
export const googleProvider = new GoogleAuthProvider();
```

### Authenticating users and retrieving tokens

Use Firebase authentication to sign in users and retrieve their ID tokens:

```typescript title="lib/auth.ts" showLineNumbers copy
import { signInWithPopup, signOut, User } from "firebase/auth";
import { auth, googleProvider } from "./firebase";

export const signInWithGoogle = async () => {
  try {
    const result = await signInWithPopup(auth, googleProvider);
    return result.user;
  } catch (error) {
    console.error("Error signing in:", error);
    throw error;
  }
};

export const getIdToken = async (user: User) => {
  try {
    const idToken = await user.getIdToken();
    return idToken;
  } catch (error) {
    console.error("Error getting ID token:", error);
    throw error;
  }
};

export const signOutUser = async () => {
  try {
    await signOut(auth);
  } catch (error) {
    console.error("Error signing out:", error);
    throw error;
  }
};
```

> Refer to the [Firebase documentation](https://firebase.google.com/docs/auth) for other authentication methods like email/password, phone authentication, and more.

## Configuring `MastraClient`

When `auth` is enabled, all requests made with `MastraClient` must include a valid Firebase ID token in the `Authorization` header:

```typescript {6} title="lib/mastra/mastra-client.ts" showLineNumbers copy
import { MastraClient } from "@mastra/client-js";

export const createMastraClient = (idToken: string) => {
  return new MastraClient({
    baseUrl: "https://<mastra-api-url>",
    headers: {
      Authorization: `Bearer ${idToken}`,
    },
  });
};
```

> **Note:** The ID token must be prefixed with `Bearer` in the Authorization header.

> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.

### Making authenticated requests

Once `MastraClient` is configured with the Firebase ID token, you can send authenticated requests:

<Tabs>
  <TabItem value="react" label="React">
    ```tsx title="src/components/test-agent.tsx" showLineNumbers copy
    "use client";

    import { useAuthState } from 'react-firebase-hooks/auth';
    import { MastraClient } from "@mastra/client-js";
    import { auth } from '../lib/firebase';
    import { getIdToken } from '../lib/auth';

    export const TestAgent = () => {
      const [user] = useAuthState(auth);

      async function handleClick() {
        if (!user) return;

        const token = await getIdToken(user);
        const client = createMastraClient(token);

        const weatherAgent = client.getAgent("weatherAgent");
        const response = await weatherAgent.generate({
          messages: "What's the weather like in New York",
        });

        console.log({ response });
      }

      return (
        <button onClick={handleClick} disabled={!user}>
          Test Agent
        </button>
      );
    };
    ```

  </TabItem>
  <TabItem value="nodejs" label="Node.js">
    ```typescript title="server.js" showLineNumbers copy
    const express = require('express');
    const admin = require('firebase-admin');
    const { MastraClient } = require('@mastra/client-js');

    // Initialize Firebase Admin
    admin.initializeApp({
      credential: admin.credential.cert({
        // Your service account credentials
      })
    });

    const app = express();
    app.use(express.json());

    app.post('/generate', async (req, res) => {
      try {
        const { idToken } = req.body;

        // Verify the token
        await admin.auth().verifyIdToken(idToken);

        const mastra = new MastraClient({
          baseUrl: "http://localhost:4111",
          headers: {
            Authorization: `Bearer ${idToken}`
          }
        });

        const weatherAgent = mastra.getAgent("weatherAgent");
        const response = await weatherAgent.generate({
          messages: "What's the weather like in Nairobi"
        });

        res.json({ response: response.text });
      } catch (error) {
        res.status(401).json({ error: 'Unauthorized' });
      }
    });
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">
    ```bash copy
    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer <your-firebase-id-token>" \
      -d '{
        "messages": "Weather in London"
      }'
    ```
  </TabItem>
</Tabs>
